gh-119180: Documentation for PEP 649 and 749 #122235

JelleZijlstra · 2024-07-24T14:29:30Z

Issue: Implement PEP 649 and PEP 749 #119180

📚 Documentation preview 📚: https://cpython-previews--122235.org.readthedocs.build/

picnixz

Haven't look at everything nor had I marked every typo but here's a first round of comments.

Doc/library/annotationlib.rst

Doc/reference/datamodel.rst

Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>

AA-Turner

Looks good, left a few comments.

General points -- the line lengths in the new text seem a bit long. Also, I wonder if it is worth covering / providing call-outs to the interactions with the annotations future? I imagine that will be something many readers will be thinking about.

A

Doc/glossary.rst

AA-Turner · 2024-07-27T17:47:27Z

Doc/library/__future__.rst

   ``from __future__ import annotations`` was previously scheduled to
-   become mandatory in Python 3.10, but the Python Steering Council
-   twice decided to delay the change
-   (`announcement for Python 3.10 <https://mail.python.org/archives/list/python-dev@python.org/message/CLVXXPQ2T2LQ5MP2Y53VVQFCXYWQJHKZ/>`__;
-   `announcement for Python 3.11 <https://mail.python.org/archives/list/python-dev@python.org/message/VIZEBX5EYMSYIJNDBF6DMUMZOCWHARSO/>`__).
-   No final decision has been made yet. See also :pep:`563` and :pep:`649`.
+   become mandatory in Python 3.10, but the change was delayed and ultimately
+   canceled. This feature will eventually be deprecated and removed. See
+   :pep:`649` and :pep:`749`.


Should we provide or link to migration guidance here, especially given that this is the first time a __future__ won't become the actual future?

Doc/library/annotationlib.rst

AA-Turner · 2024-07-27T17:56:28Z

Doc/library/annotationlib.rst

+The :mod:`!annotationlib` module provides tools for introspecting :term:`annotations <annotation>`
+on modules, classes, and functions.


Potentially this could be added later, but I think a longer narrative summary of annotationlib and where it fits in could be of use -- we jump straight into functions here. Contrast with pathlib, heapq, hashlib.

I wonder if there are words from 749 that we could incorporate? Effectively, something that briefly talks to where this module fits into the landscape, perhaps aimed at the fairly experienced user of types/inspect/typing, but someone who hasn't followed the PEPs.

Yes, I was thinking of adding that too, but ran out of energy while working on the initial version. :) I'll probably work on this later.

I wrote such a summary now, along with a historical account of annotation semantics, since that seems like something the docs should cover.

Doc/library/annotationlib.rst

Doc/library/typing.rst

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

AA-Turner · 2024-08-07T15:43:15Z

Doctest failures:

Document: library/annotationlib
-------------------------------
**********************************************************************
File "library/annotationlib.rst", line 67, in default
Failed example:
    call_evaluate_function(Alias.evaluate_value, Format.VALUE)
Exception raised:
    Traceback (most recent call last):
      File "/home/runner/work/cpython/cpython/Lib/doctest.py", line 1395, in __run
        exec(compile(example.source, filename, "single",
        ~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                     compileflags, True), test.globs)
                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "<doctest default[1]>", line 1, in <module>
        call_evaluate_function(Alias.evaluate_value, Format.VALUE)
        ~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/home/runner/work/cpython/cpython/Lib/annotationlib.py", line 421, in call_evaluate_function
        return call_annotate_function(evaluate, format, owner=owner, _is_evaluate=True)
      File "/home/runner/work/cpython/cpython/Lib/annotationlib.py", line 446, in call_annotate_function
        return annotate(format)
      File "<doctest default[0]>", line 1, in Alias
        type Alias = undefined
                     ^^^^^^^^^
    NameError: name 'undefined' is not defined
**********************************************************************

Document: library/typing
------------------------
**********************************************************************
File "library/typing.rst", line 2181, in default
Failed example:
    Alias.__value__
Exception raised:
    Traceback (most recent call last):
      File "/home/runner/work/cpython/cpython/Lib/doctest.py", line 1395, in __run
        exec(compile(example.source, filename, "single",
        ~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                     compileflags, True), test.globs)
                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "<doctest default[1]>", line 1, in <module>
        Alias.__value__
      File "<doctest default[0]>", line 1, in Alias
        type Alias = undefined
                     ^^^^^^^^^
    NameError: name 'undefined' is not defined
**********************************************************************
File "library/typing.rst", line 2185, in default
Failed example:
    Alias.evaluate_value(Format.VALUE)
Exception raised:
    Traceback (most recent call last):
      File "/home/runner/work/cpython/cpython/Lib/doctest.py", line 1395, in __run
        exec(compile(example.source, filename, "single",
        ~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                     compileflags, True), test.globs)
                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "<doctest default[3]>", line 1, in <module>
        Alias.evaluate_value(Format.VALUE)
        ~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^
      File "<doctest default[0]>", line 1, in Alias
        type Alias = undefined
                     ^^^^^^^^^
    NameError: name 'undefined' is not defined
**********************************************************************

savannahostrowski

Most of these are nits. I got curious about the PR and found some small things 🙈 !

Doc/library/annotationlib.rst

willingc

Overall, this looks good @JelleZijlstra. I'm wondering if we are going a bit too deep into implementation in the Data Model Language Reference page.

Doc/howto/annotations.rst

Doc/library/annotationlib.rst

Co-authored-by: Carol Willing <carolcode@willingconsulting.com>

JelleZijlstra · 2024-09-11T01:26:19Z

Thanks for the review @willingc! Which part do you think goes into too much detail? I looked over the data model changes and all the changes seem relevant to me.

willingc · 2024-09-11T14:05:30Z

Thanks for the review @willingc! Which part do you think goes into too much detail? I looked over the data model changes and all the changes seem relevant to me.

@JelleZijlstra I reread the data model changes again on the rendered page (instead of the diff). On the initial read, I thought there was implementation content mixed in, but I was mistaken and misled by the rST markup. Thanks for rechecking and sorry for the extra noise.

Let's 🚢 this. 😄

JelleZijlstra added 6 commits July 23, 2024 21:21

pythongh-119180: Documentation for PEP 649/749

20dcb62

Document evaluate_forward_ref

206560c

Merge remote-tracking branch 'upstream/main' into pep649-doc

edd12a2

add something

79ce456

docs for annotationlib

3f70c21

Update inspect

e297349

JelleZijlstra requested a review from AlexWaygood as a code owner July 24, 2024 14:29

bedevere-app bot mentioned this pull request Jul 24, 2024

Implement PEP 649 and PEP 749 #119180

Open

29 tasks

bedevere-app bot added the awaiting core review label Jul 24, 2024

picnixz reviewed Jul 24, 2024

View reviewed changes

JelleZijlstra and others added 4 commits July 27, 2024 09:17

Apply suggestions from code review

d52fb08

Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>

Merge remote-tracking branch 'upstream/main' into pep649-doc

4e7a2a5

More feedback

35312e7

Docs expansion

b30abbd

JelleZijlstra added the skip news label Jul 27, 2024

AA-Turner added the docs Documentation in the Doc dir label Jul 27, 2024

JelleZijlstra added 2 commits July 27, 2024 11:24

formatting

bcb6a9f

Merge remote-tracking branch 'upstream/main' into pep649-doc

c82fb66

AA-Turner reviewed Jul 27, 2024

View reviewed changes

JelleZijlstra and others added 5 commits July 27, 2024 11:49

More documentation

b4f6385

Apply suggestions from code review

6ebdce9

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

stray whitespace

52dc99e

Suggestions from Adam on evaluate_forward_ref

61eedbd

Expand docs, based on suggestion by Adam

27668ce

Merge remote-tracking branch 'upstream/main' into pep649-doc

6254e18

JelleZijlstra requested a review from willingc as a code owner September 9, 2024 23:27

doctest?

c42cb60

savannahostrowski reviewed Sep 10, 2024

View reviewed changes

expand

1873912

JelleZijlstra added 3 commits September 9, 2024 17:59

Feedback from Savannah

86001c1

fix link

c1943fa

shorter lines

889f5aa

willingc approved these changes Sep 10, 2024

View reviewed changes

Doc/howto/annotations.rst Outdated Show resolved Hide resolved

Doc/library/annotationlib.rst Outdated Show resolved Hide resolved

Doc/library/annotationlib.rst Outdated Show resolved Hide resolved

bedevere-app bot added awaiting merge and removed awaiting core review labels Sep 10, 2024

Apply suggestions from code review

6dd39fb

Co-authored-by: Carol Willing <carolcode@willingconsulting.com>

JelleZijlstra merged commit 5436d8b into python:main Sep 11, 2024
23 checks passed

bedevere-app bot removed the awaiting merge label Sep 11, 2024

JelleZijlstra deleted the pep649-doc branch September 11, 2024 14:50

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

gh-119180: Documentation for PEP 649 and 749 #122235

gh-119180: Documentation for PEP 649 and 749 #122235

JelleZijlstra commented Jul 24, 2024 •

edited by github-actions bot

Loading

picnixz left a comment

AA-Turner left a comment

AA-Turner Jul 27, 2024

AA-Turner Jul 27, 2024

JelleZijlstra Jul 27, 2024

JelleZijlstra Sep 10, 2024

AA-Turner commented Aug 7, 2024

savannahostrowski left a comment •

edited

Loading

willingc left a comment

JelleZijlstra commented Sep 11, 2024

willingc commented Sep 11, 2024

		The :mod:`!annotationlib` module provides tools for introspecting :term:`annotations <annotation>`
		on modules, classes, and functions.

gh-119180: Documentation for PEP 649 and 749 #122235

gh-119180: Documentation for PEP 649 and 749 #122235

Conversation

JelleZijlstra commented Jul 24, 2024 • edited by github-actions bot Loading

picnixz left a comment

Choose a reason for hiding this comment

AA-Turner left a comment

Choose a reason for hiding this comment

AA-Turner Jul 27, 2024

Choose a reason for hiding this comment

AA-Turner Jul 27, 2024

Choose a reason for hiding this comment

JelleZijlstra Jul 27, 2024

Choose a reason for hiding this comment

JelleZijlstra Sep 10, 2024

Choose a reason for hiding this comment

AA-Turner commented Aug 7, 2024

savannahostrowski left a comment • edited Loading

Choose a reason for hiding this comment

willingc left a comment

Choose a reason for hiding this comment

JelleZijlstra commented Sep 11, 2024

willingc commented Sep 11, 2024

JelleZijlstra commented Jul 24, 2024 •

edited by github-actions bot

Loading

savannahostrowski left a comment •

edited

Loading